What this does

Spec work for #10. No runtime yet. This is the contract that the client and the server will both implement in M2.

What was done

schema.graphql

type User {
  id: ID!
  displayName: String!
}

type Review {
  id: ID!
  user: User!        # added
  rating: Int!
  comment: String!
  createdAt: DateTime!
  updatedAt: DateTime!
}

Reviews rendered without an author was a real gap. The brief asks that user-generated data is presented, and an unattributed review does not present it. displayName is deliberately not in UpsertReviewInput, so a review cannot be attributed to a name the sender did not earn.

AGENTS.md rule 5 was wrong. It said the UUID is "sent with every mutation". myReview, isInCrate and myCrate are queries and need the identity just as much. Rewritten to cover the header, the per-request context, the anonymous fallback, and why displayName is derived server-side.

docs/architecture.md decision 5. Even had the decision right ("sends it with each request") but not the transport. This adds:

• why an X-User-Id header and not a GraphQL variable, a cookie, or Authorization
• why it goes on every request
• the missing / malformed / valid-but-new / valid behaviour table
• why displayName is derived from the UUID rather than supplied

docs/data-model.md gains the user in the user-generated data section.

Why a header and not a GraphQL variable

myReview, isInCrate and myCrate currently take zero arguments, which is deliberate. A userId argument on each would mean threading $userId through every operation and would make identity look like data when it is really transport. The header is set once by an Apollo link and read once into the context.

It is also not Authorization, because nothing here is authenticated. Anyone can send any UUID. Calling it Authorization would be misleading when we are asked to defend this in a viva.

Missing or invalid

Reads never fail because of identity state, so a bad header cannot take the search page down. Writes require it and say so rather than attributing the change to nobody.

What was tested

Validated the SDL with buildSchema:

SDL parses OK
Review fields: id, user, rating, comment, createdAt, updatedAt
User fields:   id, displayName
root args mentioning user: none - identity comes from context
Album.myReview()      -> Review
Album.isInCrate()     -> Boolean!
Query.myCrate(first,after) -> CrateConnection!
all user-scoped fields take zero args: true

Also pnpm format:check, pnpm lint, pnpm typecheck and pnpm test (3 tests) all pass.

Closes

Closes the spec half of #10. The implementation (Apollo link, context, lazy user row) is the remaining half and needs server/ from #6.

Related

@evenkkl decision 5 in docs/architecture.md is yours and I extended it rather than replacing it. Please check the transport section reads the way you intended.